Added AGENTS.md instructions and SKILLS.md#1921
Conversation
rozza
force-pushed
the
JAVA-6143
branch
2 times, most recently
from
4c75537 to
935f140
Compare
rozza
changed the title
|
Followed general guidelines from: https://wiki.corp.mongodb.com/spaces/MMS/pages/499158370/Making+a+Repo+Agent+Ready AGENTS.md: The ConstitutionAGENTS.md is a markdown file at the root of the repository. Every AI agent — Augment, Claude Code, Cursor — reads it automatically at the start of every session. This means every token in AGENTS.md is loaded into the agent's context window every single time. The context window has a budget. Frontier models reliably follow ~150-200 instructions, and tool system prompts consume a significant share before your AGENTS.md even loads. Overstuffing AGENTS.md degrades the quality of all instructions — not selectively. Brevity is load-bearing. What belongs in AGENTS.mdCore development principles (style, testing, safety rules) What does NOT belong in AGENTS.mdDetailed workflows for specific tasks (use a skill) |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 52 out of 53 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
rozza
requested review from
katcharov and
strogiyotec
and removed request for
strogiyotec
|
We had a bit of discussion about this in the AI/ML-sync meeting yesterday. My approach has been to use very minimal agents files (for Junie, Augie, and Claude) because I don't think it is clear what is:
I think we've all seen harmful changes--for example, telling it about tests and then having the agent get caught up attempting to run them all the time. Things that are not harmful but also not very useful (the benign category) can end up being accidentally harmful by taking up context space and thereby forcing something important out. We can discuss these things on a case-by-case basis, but I think that means starting small and understanding the impacts of the changes made. Another approach is for each platform team to do something different and then we all compare notes later. |
katcharov
left a comment
katcharov
left a comment
There was a problem hiding this comment.
Partial review. Agree with @ajcvickers points above. There is a fair bit of content here, and I am not sure how we can validate it.
|
So I think before going further, an ideological approach has to be agreed upon. Do we add skills at all initially? We could .gitignore the skills directory and then manually add them on a one by one basis in other PR's? That approach is handy and would allow users to have test their own skills without risk of accidently adding to the repo. Note the request for local skills anthropics/claude-code#31155 has been closed so there is no local repo skills pattern other than via .gitignore. We can start small - just the AGENTS.md files explaining the source code and how to compile and run the tests. This is useful to stop claude trying to use sbt instead of gradle everytime it tries to do anything in scala.
|
|
I made some changes after iterating with Claude. Full report of the final outcomes: https://gist.github.com/rozza/1a474291735bac0a28e399c59a977db2 |
|
@rozza I think you should continue with this approach and on the C# driver we will start more minimal, and then let's revisit how things are working in a few weeks. |
|
@katcharov please re-review. See: https://gist.github.com/rozza/1a474291735bac0a28e399c59a977db2 for the claude report on the latest iteration. |
rozza
requested review from
dariakp and
nhachicha
and removed request for
katcharov
@rozza If this is accurate, should the CLAUDE.md pointer files be removed? |
dariakp
left a comment
dariakp
left a comment
There was a problem hiding this comment.
With respect to the overall content, this makes sense to me. I don't think we have to get it perfect. I didn't see anything obviously wrong here. The one note I have is that you mentioned in a previous comment that CLAUDE code does discover AGENTS.md - if so, should the rest of the CLAUDE.md pointers to AGENTS.md be removed?
|
@dariakp - I updated the comment. Unfortunately the CLAUDE.md files are needed. I got a false positive from Claude when I asked if it read the AGENTS.md files - it proceeded to read them and then tell me yes - which caught me out. Confirmation: https://code.claude.com/docs/en/memory#agents-md |
rozza
force-pushed
the
JAVA-6143
branch
2 times, most recently
from
96268d9 to
1646567
Compare
|
@nhachicha I rebased folded all the commits into a single commit. One main change was some of the skills I had were really references - so split them out so they will still be contextually loaded as required. |
Adds structured AI agent documentation across the MongoDB Java Driver using the AGENTS.md convention — an open standard for providing codebase context to AI coding agents. - Root AGENTS.md with build commands, style rules, testing policy, API design guidelines, safety-critical code boundaries, and dependency rules - Per-module AGENTS.md files (bson, driver-core, driver-sync, etc.) with module-specific packages, dependencies, and patterns - CLAUDE.md files that reference AGENTS.md (for Claude Code compatibility) - `.agents/references/` for passive knowledge (contextually loaded): project-guide, style-reference, api-design, testing-guide, spec-tests - `.agents/skills/` for procedural workflows: evergreen (CI validation), sync-agents-docs (documentation sync checklist) - `scripts/symlink-claude-md.sh` for maintaining CLAUDE.md symlinks - References over skills for static knowledge: references are loaded contextually based on description relevance rather than requiring explicit invocation. This avoids bloating every conversation with all documentation while still surfacing it when needed. - Flat file layout for references (.agents/references/api-design.md) rather than directory-per-reference (.agents/references/api-design/REFERENCE.md): simpler structure; supplementary files use name-prefixing (e.g. testing-guide-examples.md) instead of subdirectories. - Markdown links (See [name](path)) rather than @ syntax for referencing from AGENTS.md: @ auto-includes file contents on every load, which defeats contextual loading. Links let agents follow them on demand. - Skills retained only for procedural workflows that have tool constraints (allowed-tools) or explicit trigger conditions (disable-model-invocation), not for passive knowledge lookup. JAVA-6143
nhachicha
left a comment
nhachicha
left a comment
There was a problem hiding this comment.
This looks great 🎉
I did additional review via Glean (deep research) & Claude review, and summarised them below. Most of them could be dismissed or implemented in a future round of improvements...
PR review concerns
-
High — Build / Gradle command guidance may be inaccurate or misleading
- Examples called out in review include
docsvsdoc, generated build config task names, and exact commands shown to agents. - Action: Verify every documented command against the actual Gradle build and keep only mechanically correct task names / invocation patterns.
- Examples called out in review include
-
High — Formatting / Spotless guidance may not match the build
- There is potential mismatch around
checkvsspotlessApply/spotlessCheck, and whether Java is actually formatted by Spotless. - Action: Re-audit formatting docs against the Gradle conventions and rewrite them to reflect the exact task dependencies and formatter coverage.
- There is potential mismatch around
-
High — Some module/package references may be wrong or misleading
- In particular,
mongodb-cryptanddriver-legacywere called out as possibly referencing the wrong packages / surfaces. - Action: Verify all referenced packages/classes against the current codebase and update any incorrect guidance before merge.
- In particular,
-
High —
driver-core/AGENTS.mdmay make an incorrect dependency claim- The stated dependency on
bson-record-codecmay not match the actual dependency graph. - Action: Verify the dependency list against
driver-core/build.gradle.kts; ifbson-record-codecis optional, label it as optional, and if it is not a dependency, remove it.
- The stated dependency on
-
Medium —
api-design.mdappears too thin / possibly truncated- It seems to stop after the “Key Patterns” section and is missing some high-value driver-specific guidance.
- Action: Add guidance for
@Deprecatedlifecycle,@Alpha/@Betaremoval expectations, commonly misused patterns likeMongoNamespace/WriteConcern/ReadPreference, and when to use@Sealedvs related patterns.
-
Medium — The API design reference is still too generic in places
- Some of the content reads like general software design advice rather than Java-driver-specific guidance.
- Action: Trim generic principles and replace them with concrete driver-specific rules (annotation usage, public/internal API rules, module ownership, sync/async expectations).
-
Medium —
scripts/symlink-claude-md.shhas unsafe / confusing behavior- Concerns include name vs implementation mismatch, possible deletion of local files, and path sensitivity.
- Action: Either make it a true symlink script with safe repo-root handling, or rename/document it clearly and add safeguards so it only touches generated files.
-
Medium —
symlink-claude-md.shis not wired into a reliable workflow- As written, contributors/agents can forget to run it and commit
AGENTS.mdchanges without matchingCLAUDE.mdupdates. - Action: Either wire it into a pre-commit hook / install task, or explicitly document the required invocation point (
before git addvsbefore commit) and enforce that convention in the README.
- As written, contributors/agents can forget to run it and commit
-
Medium —
sync-agents-docslooks like a non-executable checklist disguised as a skilldisable-model-invocation: truewith no allowed tools means the agent cannot actually reason about which checklist items apply.- Action: Either remove
disable-model-invocation: trueso the agent can reason about relevance, or document clearly that this is intentionally a manual checklist only.
-
Medium — There may still be duplication across root AGENTS.md, per-module AGENTS.md, and references/skills
- This increases maintenance cost and risks stale or conflicting instructions.
- Action: Do one final DRY pass and move repeated detail into references, keeping AGENTS.md files focused on always-needed guidance.
-
Medium — The
bom/module is listed but has noAGENTS.md- Even though it is low complexity, agents can still make dependency-management mistakes there.
- Action: Add a minimal
bom/AGENTS.mdstating that dependency versions belong in the version catalog / central dependency management, not inline in module build files.
-
Low —
driver-lambda/andgraalvm-native-image-app/are listed in the project guide but have noAGENTS.md- This may confuse agents about whether they are intended development targets.
- Action: Either add minimal AGENTS files, or explicitly note in the project guide that these modules are intentionally undocumented / not normal development targets.
-
Low — The README’s reference to
agentskills.ioshould be treated carefully- If this is meant to be a long-term standards reference, it is worth confirming that this is the canonical external link the repo wants to depend on.
- Action: Confirm the project wants to pin to
agentskills.iolong-term, or reference the underlying spec / canonical source directly if that is more stable.
-
Low —
testing-guide-examples.mdmay contain a Kotlin mocking example contributors will copy incorrectly- The
@Mockexample looks suspicious unless it is tied to a specific framework setup. - Action: Fix the snippet to use the intended mocking style, or add a brief note if the pattern is framework-specific.
- The
-
Low — Markdown tables need a final rendered sanity check
- Some table-formatting concerns were raised during review and are easy to miss in raw diff form.
- Action: Review all new tables in GitHub’s rendered view and fix any remaining formatting issues.
-
Low — Overall AGENTS content density should stay tightly controlled
- The root and module AGENTS files should remain minimal so they do not become high-token, low-signal context.
- Action: Keep AGENTS.md minimal and move anything not needed in most sessions into references or skills.
Add AI agent instructions using the AGENTS.md open standard
Adds structured AI agent documentation across the MongoDB Java Driver
using the AGENTS.md convention — an open standard for providing
codebase context to AI coding agents.
Root AGENTS.md with build commands, style rules, testing policy, API
design guidelines, safety-critical code boundaries, and dependency rules
Per-module AGENTS.md files (bson, driver-core, driver-sync, etc.) with
module-specific packages, dependencies, and patterns
CLAUDE.md files that reference AGENTS.md (for Claude Code compatibility)
.agents/references/for passive knowledge (contextually loaded):project-guide, style-reference, api-design, testing-guide, spec-tests
.agents/skills/for procedural workflows:evergreen (CI validation), sync-agents-docs (documentation sync checklist)
scripts/symlink-claude-md.shfor maintaining CLAUDE.md symlinksReferences over skills for static knowledge: references are loaded
contextually based on description relevance rather than requiring
explicit invocation. This avoids bloating every conversation with all
documentation while still surfacing it when needed.
Flat file layout for references (.agents/references/api-design.md)
rather than directory-per-reference (.agents/references/api-design/REFERENCE.md):
simpler structure; supplementary files use name-prefixing
(e.g. testing-guide-examples.md) instead of subdirectories.
Markdown links (See name) rather than @ syntax for referencing
from AGENTS.md: @ auto-includes file contents on every load, which
defeats contextual loading. Links let agents follow them on demand.
Skills retained only for procedural workflows that have tool constraints
(allowed-tools) or explicit trigger conditions (disable-model-invocation),
not for passive knowledge lookup.
JAVA-6143